[V5] Init Content API RFC #53

alexandrebodin · 2023-09-05T06:52:31Z

Introduce the Content API changes for v5

You can read it here

strapi-cla · 2023-09-06T17:55:21Z

All committers have signed the CLA.

abdallahmz · 2023-09-06T18:29:43Z

rfcs/xxxx-v5-content-api.md

+
+### Endpoints
+
+Based on the [Database changes planned](https://github.com/strapi/rfcs/pull/52),we will now mainly work with the `documentId` within the API.


I am curious about how users can make modifications to a particular entry using the API, given that it accepts documentId as input. For example, let's say I want to delete my entry with entryId : how would it be done with the new API ? (Similar questions can be raised for the other endpoints.)

One potential approach to address this issue (if it's considered as one) could be to introduce a new endpoint. Either /api/:contentType/document/:documentId to keep the old API working as is, or add /api/:contentType/entry/:entryId to at least have an endpoint similar to the old behavior. (edit: another idea is /api/:contentType/:documentId/:entryId though it might be harder to use for no real value)

From my current understanding, multiple entries can refer to the same documentId, and a "document" instance doesn't truly exist by itself (e.g., there isn't a structure like { documentId: '123', entries: [...] }).

If I misunderstood any aspect (I don't have deep expertise in the specifics of your codebase), feel free to ignore my message, though your clarifications will be appreciated. :)

svrin · 2023-09-07T11:44:37Z

rfcs/xxxx-v5-content-api.md

+      "documentId": "clkgylw7d000108lc4rw1bb6s",
+      "entryId": 1,
+      "name": "Category A",
+      "meta": {


This clashed with a component or field having the name "meta", is the later then shadowed?

svrin · 2023-09-07T11:45:19Z

rfcs/xxxx-v5-content-api.md

+      "name": "Category A",
+      "meta": {
+        "locale": "en",
+        "createdAt": "2023-01-01T00:00:00.000Z",


i think publication_state should be added to meta as well. (or all pivot elements)

svrin · 2023-09-07T11:46:50Z

rfcs/xxxx-v5-content-api.md

+# Unresolved questions
+
+- Should we use `id` or `documentId` in the new response format.
+- Should we use `entryId` or `entityId` to represent the underlying Ids to use for low level relations


The API should not rename fields, so if you want to use either of it, the database should be renamed from id to e?id as well.

svrin · 2023-09-07T11:48:16Z

rfcs/xxxx-v5-content-api.md

+
+Pros:
+
+- No conflicts between user & system attributes


How can there be conflicts anyway? All fields are added flat to the database table, so noone can name a field created_at.

The reference is to conflicts from existing projects with a field like "publishedBy" or "release" that do not exist as internal fields today but if upgraded to v5 would be a breaking change to those users and result in a conflict. Likewise if we decide to add any other system/internal fields during the v5 lifecycle.

svrin · 2023-09-07T11:49:07Z

rfcs/xxxx-v5-content-api.md

+| -------- | ----------------------------------------------- | ----------------------------------------------------------------------- |
+| `GET`    | `/api/:contentType`                             | Find a list of documents                                                |
+| `POST`   | `/api/:contentType`                             | Create a document                                                       |
+| `GET`    | `/api/:contentType/:documentId`                 | Find a document                                                         |


I think both should be possible:

/api/:contentType/:documentId
and
/api/:contentType/:entityId.

svrin · 2023-09-07T11:51:42Z

rfcs/xxxx-v5-content-api.md

+
+| Method   | Url                                             | Desc                                                                    |
+| -------- | ----------------------------------------------- | ----------------------------------------------------------------------- |
+| `GET`    | `/api/:contentType`                             | Find a list of documents                                                |


This feels like filtering for pivot states will be baked into filters api. I think it would benefit, if there would be clear GET endpoints for like "all french documents" or "all live documents".

roelbeerens · 2023-09-08T16:23:34Z

I'm not sure where to comment on the RFC, so I'll add my comments here:

The simplified API response is a welcome feature 🥰. I do however have my concerns about the usage of 'documentId'. It isn't clear to me this response will also be used for the GraphQL response, but last I checked, using something like Apollo with caching, requires an 'id' field. Maybe this is configurable, but next to that, I don't really see the benefits of using something other than 'id'.

Rest looks super solid!

ComfortablyCoding · 2023-09-11T01:56:46Z

As mentioned above I would also advocate for keeping id as id instead of renaming it to documentId. id is a term everyone is already familiar with and understand what it is for (uid of a record).

I would say we keep ID for the uid of every record and the some other field (entryId sounds good to me) for indicating the id for the base record.

alexandrebodin · 2023-09-15T13:51:21Z

Thank you all for your comments 🚀 We have an updated version coming next week that thanks to your notes 🔥

alexandrebodin · 2023-09-19T07:31:00Z

Hello there 👋 There RFC was just updated to clarify certain differences between internal & meta attributes & show the different options that we have. If you can share what you think of each of them for your own DX that would be great 💯

ComfortablyCoding · 2023-09-20T01:12:41Z

The updated version looks a lot better now!

Given the option return formats I prefer option 2, but with it being meta not internal

Reasoning

recognizable property from v4
"internal" can be seen as something that should not be touched or access normally which is not the intention.
common indicator of meta data of a record which most of the data being stored there will be.
i dont see it being nested one level deep as an issue. i actually prefer it this way
do not see a user confusing what is defined on the model and what is being shown in the meta. A lot of education has already been done via v4 on what meta is and what it contains.
can also put in the metadata information mentioned later on in the spec, having all this "meta" info in one place makes the most sense to me.

Looking forward!

Boegie19 · 2023-09-20T14:03:55Z

This gives me an other question. no matter what option you do. how would you for come name conflicts on the DB layer.
Only way I see this working is by prefixing the user generated content.

Also lets say we go for option 3. would that mean none can start a string with a _ or $ since if you where to allow for that that would mean you can still have conflicts.

alexandrebodin · 2023-09-21T07:14:11Z

This gives me an other question. no matter what option you do. how would you for come name conflicts on the DB layer. Only way I see this working is by prefixing the user generated content.

Also lets say we go for option 3. would that mean none can start a string with a _ or $ since if you where to allow for that that would mean you can still have conflicts.

Depending on the option we go with for the DX here we will of course adapt the DB layer to use prefixes when necessary. It would of course mean we forbidden those prefixes to be used (which is already the case)

Boegie19 · 2023-09-21T18:41:57Z

Other question I see no where in the RFC how you would reference a specific entry in the document.

alexandrebodin · 2023-09-22T08:33:23Z

Other question I see no where in the RFC how you would reference a specific entry in the document.

the document is a virtual thing fetching a document will always return the content of a single entry. (Based on filters provided or default filters)

if you do (just an example) ?locale=en&state=draft you will get the draft entry for the english locale and by default you would get your default locale and the published version of your document.

Boegie19 · 2023-09-27T09:39:53Z

Other question I see no where in the RFC how you would reference a specific entry in the document.

the document is a virtual thing fetching a document will always return the content of a single entry. (Based on filters provided or default filters)

if you do (just an example) ?locale=en&state=draft you will get the draft entry for the english locale and by default you would get your default locale and the published version of your document.

I think you should also be able to request by id since how would you get a record where a new one has been posted over so it no longer is first in any combination of keys also there needs to be an endpoint that lists all enteries in a document.

alexandrebodin · 2023-10-09T16:20:36Z

Hello everyone.

Thank you all for your comments 💯

We will go ahead and update this RFC to reflect the option we are going to move forward with and merge it in the upcoming days.

After carefully considering the different Options, Option 1 is the most viable one for v5 and is the one we will be moving forward with.

Here are the main driving deciders

It provides the better DX for end users
- Removes as much nesting as possible
- Simpler query syntax & selecting
- Less magic = less error prone
By managing reserverd words & pre-reserving words we can prevent conflicts for upcoming features and until another major comes along where we can introduce new sets of reserved words.
Offers the possiblility to incrementally add new features by reserving a specialized prefix for all new feature (e.g strapi_)
Allows introducing Option 2 or 3 without breaking changes by reserving a prefix & a meta/internal key if it becomes a requirement

martinbeentjes · 2023-11-15T07:02:40Z

I have been using Strapi for a short while now, and the nesting of attributes has been somewhat a hassle. Luckily, with ChatGPT nowadays the generation of all data classes (I consume in Kotlin) made it easier.

For a smooth migration, I think the best option is to supply a request parameter that allows for choosing the format. That way, all consumers of content can prepare for a new version and then a v5.3.x for example can migrate the version to be the new one by default.

What I am missing, how would the localizations be added under $.localizations here, just as flattened as the root level? Or is that to be defined?

alexandrebodin added the v5 label Sep 5, 2023

Init Content API RFC

16a3ea3

alexandrebodin force-pushed the v5/content-api branch from 3382ff8 to 16a3ea3 Compare September 5, 2023 06:53

derrickmehaffy mentioned this pull request Sep 6, 2023

Notice: Requesting community feedback on v5 RFCs strapi/strapi#17958

Closed

abdallahmz reviewed Sep 6, 2023

View reviewed changes

svrin reviewed Sep 7, 2023

View reviewed changes

alexandrebodin force-pushed the v5/content-api branch 2 times, most recently from 8f5f31e to 8badeb6 Compare September 19, 2023 07:29

Update RFC

6fabcb9

alexandrebodin force-pushed the v5/content-api branch from 8badeb6 to 6fabcb9 Compare September 19, 2023 07:29

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[V5] Init Content API RFC #53

[V5] Init Content API RFC #53

alexandrebodin commented Sep 5, 2023 •

edited

Loading

strapi-cla commented Sep 6, 2023 •

edited

Loading

abdallahmz Sep 6, 2023 •

edited

Loading

svrin Sep 7, 2023

svrin Sep 7, 2023

svrin Sep 7, 2023

svrin Sep 7, 2023

derrickmehaffy Sep 21, 2023

svrin Sep 7, 2023

svrin Sep 7, 2023

roelbeerens commented Sep 8, 2023

ComfortablyCoding commented Sep 11, 2023

alexandrebodin commented Sep 15, 2023

alexandrebodin commented Sep 19, 2023

ComfortablyCoding commented Sep 20, 2023 •

edited

Loading

Boegie19 commented Sep 20, 2023 •

edited

Loading

alexandrebodin commented Sep 21, 2023

Boegie19 commented Sep 21, 2023 •

edited

Loading

alexandrebodin commented Sep 22, 2023 •

edited

Loading

Boegie19 commented Sep 27, 2023

alexandrebodin commented Oct 9, 2023

martinbeentjes commented Nov 15, 2023


		### Endpoints

		Based on the [Database changes planned](https://github.com/strapi/rfcs/pull/52),we will now mainly work with the `documentId` within the API.

[V5] Init Content API RFC #53

Are you sure you want to change the base?

[V5] Init Content API RFC #53

Conversation

alexandrebodin commented Sep 5, 2023 • edited Loading

strapi-cla commented Sep 6, 2023 • edited Loading

abdallahmz Sep 6, 2023 • edited Loading

Choose a reason for hiding this comment

svrin Sep 7, 2023

Choose a reason for hiding this comment

svrin Sep 7, 2023

Choose a reason for hiding this comment

svrin Sep 7, 2023

Choose a reason for hiding this comment

svrin Sep 7, 2023

Choose a reason for hiding this comment

derrickmehaffy Sep 21, 2023

Choose a reason for hiding this comment

svrin Sep 7, 2023

Choose a reason for hiding this comment

svrin Sep 7, 2023

Choose a reason for hiding this comment

roelbeerens commented Sep 8, 2023

ComfortablyCoding commented Sep 11, 2023

alexandrebodin commented Sep 15, 2023

alexandrebodin commented Sep 19, 2023

ComfortablyCoding commented Sep 20, 2023 • edited Loading

Boegie19 commented Sep 20, 2023 • edited Loading

alexandrebodin commented Sep 21, 2023

Boegie19 commented Sep 21, 2023 • edited Loading

alexandrebodin commented Sep 22, 2023 • edited Loading

Boegie19 commented Sep 27, 2023

alexandrebodin commented Oct 9, 2023

martinbeentjes commented Nov 15, 2023

alexandrebodin commented Sep 5, 2023 •

edited

Loading

strapi-cla commented Sep 6, 2023 •

edited

Loading

abdallahmz Sep 6, 2023 •

edited

Loading

ComfortablyCoding commented Sep 20, 2023 •

edited

Loading

Boegie19 commented Sep 20, 2023 •

edited

Loading

Boegie19 commented Sep 21, 2023 •

edited

Loading

alexandrebodin commented Sep 22, 2023 •

edited

Loading